InterCal is a simple program with (I hope) an intuitive interface. You should be able to familiarize yourself with all the options in a few minutes simply by running the program and playing around. (The only exceptions might be the handling of editing the year field, and controlling the display when the Mayan is the primary calendar.) Nevertheless, this Users’ Guide tries to be a complete reference which can be turned to when a question arises.
Explanations of the implemented calendar systems, and some definitions of terms (such as era), can be found in the accompanying document Calendar System Facts.
InterCal defines two special dates, both of which can be manipulated by the user. The displayed date controls the month calendar display which dominates the main window. The selected date is used to serve as a marker which can be returned to at any time using the “Jump To Selected” command under the Options menu. The Julian Date window shows its equivalent in all implemented calendar systems. So if you want to know what your birthday is (for example) in all implemented systems, make it the selected date and show the Julian Date window. The displayed date and the selected date do not have to be the same, although they may be.
2. STARTUP STATE
InterCal has three windows which can be left permanently open, plus some modal dialogs and Alerts which appear and disappear as they are needed. The main window (described in detail in §3) is always visible. Both its size and position are adjustable. The “date” window (described in §4.4.1) is not visible at startup. Its visibility is controlled by the user. Its size is not adjustable but its position is. The “Mayan Correlations” window (described in §4.4.6) is also not visible at startup. Its visibility is controlled by the user. Both its size and position are adjustable.
The program tries to draw all windows with exactly the same size and position which they had the last time the program was run. If that cannot be done for any reason, the program reverts to its defaults. The default for the main window is near the upper left corner of the main screen, with a size which nearly fills it. However, a maximum size is built in so that the window will never exceed the size necessary to display all of its contents at once. The defaults for the date window and the Mayan Correlations window are to be centered on the main screen.
The initial calendar system is Western Historical. The initial secondary calendar system (see below for definition of a secondary calendar) is “none”. The year and month are chosen so that today’s date is visible and selected. Since it is selected, it is highlighted using reverse video.
A variety of Christian, Jewish, and Islamic holidays can be highlighted under user control. The program attempts to use the same settings which were in effect the last time the program was executed. If it cannot do so, it reverts to the defaults.The default is to highlight the following religious holidays/holy days: Western Easter, Christmas, Rosh Hashonah, Yom Kippur, Hanukah, Passover, first day of Ramadan, Islamic New Year, Milad-an-Nabi (birthday of the Prophet), and the start of ‘Id al-Fitr (festival after Ramadan is over). (It may seem strange to most people to highlight Christmas, since it is a fixed feast. But it is only fixed in the Gregorian calendar and its relatives! All Jewish and Islamic holy days are fixed in their respective calendars. Easter and Pentecost are the only truly movable feasts handled by InterCal.) If the current screen is operating in color mode, Christian holidays are shown in yellow, Jewish in blue, and Islamic in red. I chose these colors from among the basic eight colors provided in the very first version of QuickDraw. If the current screen is monochrome, holidays are highlighted using three of the standard patterns found in the system resource file.
The Mayan correlation and the values of the Mayan controls (Move to future or past; edit together as calendar round) are remembered from the last time the program was run. As released, InterCal uses the modified Goodman-Martinez-Thompson correlation, which has Long Count 0.0.0.0.0 corresponding to Julian Day 584285 (September 8, 3114 B.C. Julian = August 13, 3114 B.C. Gregorian). “Move to future” is on. “Edit together as Calendar Round” is not checked.
3. THE MAIN WINDOW
3.1. Static Calendar System Displays
The main window is divided into several panes: the primary and secondary calendar system labels; controls for specifying the displayed date; and the month calendar.
On the top line at the left, in a static (not editable) text area, the current choice of primary calendar system is displayed. To its right the current choice of secondary system is shown. Most of the rest of the window contents refer to dates in the primary calendar system. The secondary system (if there is one) is used to directly compare dates in one system to the same dates in the other system. See §4.3, “Primary and Secondary Menus”, for more details.
3.2. Specifying the Displayed Date
Controls for manipulating the displayed date occupy the next few lines in the main window. Two types of calendars, with basically different structures, are implemented by InterCal. Their method of controlling the displayed date differs accordingly. Most calendars are linear (as explained in Calendar System Facts). Such calendars have years and eras. Dates follow a linear progression. All calendars implemented by InterCal except the Mayan fall into this category. The Mayan is a cyclic calendar and is also really three calendars in one. The controls for determining the displayed date in the Mayan calendar look and act completely differently from those for all other implemented calendars.
3.2.1. Typical Linear Calendar Systems
The month, era, and year selection controls appear near the top of the main window whenever a linear calendar is the primary system.
3.2.1.1. Month/Era Selection
The first line in the control area is in larger type. At the left is the name of the month being displayed. At the right is the era of the displayed month. Both the name of the month and the name of the era are actually entries in popup menus. The user can use the menus to switch to a different month in the same year, or to switch eras while keeping the month and the absolute value of the year the same. These menus are written using the Avant Garde font, which I believe is available on most Macintosh systems.
Immediately to the left and right of the month name/menu are large arrows. They are blue or dark gray depending on your monitor’s color mode. These arrows act like buttons. They can be clicked once, or pressed (click and hold down the mouse). The left-pointing arrow decreases the month, while the right-pointing arrow increases the month. When the mouse is released, the rest of the window is redrawn to match the newly-selected month. It is OK to press so long that the months cycle past a year boundary. The program works correctly even if the era happens to change while pressing a month-changing button.
Thus there are two alternate ways to change months. The pop up menu might be most convenient for jumping from one end of a year to the other, whereas the arrow buttons might be best for moving a few months at a time.
3.2.1.2. Year Selection
Centered in the next line down, in medium type, is a box displaying the absolute value of the year. (To determine the sign of the year, you need to look at the era display.) It is surrounded by two arrow buttons. These buttons act similarly to the month buttons described above, except that they decrement or increment the year. The down-pointing arrow at the left decreases the actual value (not the absolute value) of the year. Thus it takes you towards the past. The up-pointing arrow at the right increases the actual value of the year, taking you towards the future.
The arrow buttons are only useful for moving a few years at a time. In order to enable large jumps in time, the year displayed in the box is an editable text field. The idiosyncrasies of editing the text field which specifies the year may be confusing. That is the primary reason I felt it was worth writing this Users’ Guide.
You can select text or place the insertion cursor wherever you want, and then follow normal text editing conventions to adjust the year to almost any value you desire. While you are doing this, the edit menu becomes active, permitting one-step undo/redo, cutting and pasting, and deletion of characters. You signal InterCal that you are finished editing the year by hitting either the Return or the Enter or the Tab key. If you change your mind while editing, the Escape key or Cmd-period ends your editing session and restores the year to the value it had before you started editing.
Editing the year normally leaves the month unaffected. However, luni-solar calendars have years with differing numbers of months and this may force a change of month. For example, if you are in the Jewish calendar displaying Adar I 5755 A.M. and jump to a non-leap-year, such as 5754 A.M., the month will change to Adar. Similarly, jumping from a leap year in the Elliott calendar, while displaying the month of Anthony, to a non-leap-year causes the month to switch to Ericka. It doesn’t matter whether the arrow buttons or the editable text field are used to change years—the same rule applies.
I wanted the user to be able to jump immediately from any year to any other year (within limits specified below) in a single editing step. This led me to a slight problem—namely, the fact that (in keeping with good calendrical conventions) the box is displaying the absolute value of the year. What if the user wants to jump to a year in the other era? What if he/she doesn’t? Of course you could always do the job in two steps, using the era popup and editing the year text box. But that would be inconvenient. I eventually settled on the following rules:
a) If the user simply manipulates the numbers in the year without providing an explicit sign (plus or minus), the era remains the same. As an example, if you are in April 4956 B.C. and edit the year box to read “111193”, you will be taken to April 111193 B.C.
b) If the user explicitly enters a sign immediately before the year (no spaces permitted) the era is forced to agree with the entered sign (which will then disappear from the display). For example, if you are displaying April 4956 B.C. and edit the year to read “+111193” you will be taken to 111193 A.D. In either case [a] or [b], the final year display will read simply “111193”, but the era display in the two cases will be different, as will (usually) the month calendar itself.
3.2.2. Mayan Calendar Display Controls
The Mayan controls appear whenever the Mayan is the primary system. They show the displayed date in each of the three different Mayan Calendars—the Long Count, the Tzolkin cycle, and the Haab cycle. Any of the three can be manipulated to change the displayed date as described below. Once one has been changed, the program updates the entire display so that the dates in all three Mayan calendars (and the month calendar display) agree.
3.2.2.1. The Long Count
The Long Count is displayed in large type at the left of the controls pane. It always contains the full 8 vigesimal digits (see Calendar System Facts for details—InterCal uses 8 digits, not the usual five, to cover long time spans). Each digit is separated from the others by a period. The Long Count is an editable text field which behaves much like the year field described in §3.2.1.2 above. The same keys are used to terminate editing and the same editing capabilities are available. If the format of the Long Count is not acceptable when you press Return, Enter, or Tab an alert appears and the old value of the Long Count is restored. If the format is acceptable, the main window display is updated immediately.
The rules for a valid Long Count are:
1) A sign may optionally precede the first digit. If no sign is present the Long Count is presumed to be non-negative.
2) There must be exactly 8 vigesimal digits separated by exactly seven periods. Leading zeroes, if applicable, are required.
3) Each digit must be in the range 0–19 inclusive, except the second digit from the right is restricted to 0–17 inclusive.
4) If the Long Count value is too large another alert will appear. Dates much above 1.17.5.0.0.0.0.0 would cause overflow and lead to garbage results in the calculations.
5) Except for the separating periods and the optional sign before the first digit, non-numeric characters are forbidden.
Note that changing the displayed date in this way has no effect whatsoever on the selected date.
3.2.2.2. The Tzolkin Cycle, Haab Cycle, and Calendar Round
The Tzolkin date and the Haab date are both displayed at the right of the Long Count. At the extreme right of the pane are two radio buttons and a check box. Remember that both the Tzolkin and Haab calendars are cyclic, with no year associated with them. InterCal assumes that when you change a Tzolkin or Haab date you want to go to the next Julian Day having the specified Tzolkin or Haab date. The radio buttons, which can be reset at any time, control whether you go to the next date in the past or the next in the future. The check box determines whether you wish to edit the Tzolkin date or the Haab date in isolation (when the box is unchecked) or together as a Calendar Round date.
The Tzolkin day name is actually a pop up menu which can be used to modify the Tzolkin date. The Tzolkin day number is an editable text field which permits only unsigned integers in the range 1–13 inclusive. The usual rules for terminating the editing of the text field apply.
The Haab month name is also a pop up menu, used for changing the Haab month. The Haab day is another editable text box, which accepts only unsigned integers in the range 0–19 inclusive (0–4 if the “month” is Wayeb).
Note that, unlike in linear calendars, you have control down to the day (not just month) of displayed date. If the Haab displayed date is, for example, 6 Mol, and you change the Haab day from 6 to 7, what happens depends critically on the setting of the past and future radio buttons. If “Move to future” is selected, changing from 6 to 7 has only a slight effect on the main window display. The Haab day text field will change, the Long Count will increment by 1, and the Tzolkin day number and name will increment by one each. But the big month display which fills most of the window will not change. But if “Move to past” is on, changing from 6 to 7 moves you 364 days into the past. The change is especially noticeable if you have a secondary calendar in force. Similarly, accepting a “change” of the Haab or Tzolkin date of zero (no change) transports you one full cycle into the past or future.
Since both Tzolkin and Haab are cycles, it often is not intended to change just one part of a date. For that reason, starting to edit either the Haab or Tzolkin date places the program into a special mode which treats the Tzolkin and Haab controls like a modal dialog. The Long Count and the “Calendar Round” check box are deactivated and will not accept changes. The month display (described later) will not accept clicks. If the date window and/or the Mayan Correlations window (described later) happen to be visible, they temporarily disappear. If the “Calendar Round” check box is not checked, either the Tzolkin or the Haab controls are also deactivated (whichever was not modified). Two buttons appear at the immediate left of the Haab controls. One is labeled OK and the other is Cancel. You can continue to change whichever of the Haab and Tzolkin controls are still active while the rest of the display remains frozen. Clicking on OK accepts the changes, updates the entire display, re-shows the date and correlations windows if applicable, and puts the program back into its normal mode. Clicking Cancel restores the Tzolkin and/or Haab dates to what they were before you started modifying them, and then acts the same way as OK.
Note that it is not possible to make large jumps in time using the Haab/Tzolkin controls. You are limited to jumps of 365 days, 260 days, or (if the Calendar Round check box is checked) about 52 years. Large jumps can be made using the Long Count field or by going into the date window, modifying the selected date, and then using the Jump To Selected menu command. (These latter methods are described in detail later in this Users’ Guide.)
If the Calendar Round check box was unchecked when you started editing, any change to the Haab or Tzolkin date is acceptable. Whichever you did not edit will be updated by the program to agree with the new choice. If the Calendar Round check box was checked, it is quite possible you will specify an impossible Haab-Tzolkin combination. In this case a modal dialog window appears and offers you several choices. You can Try Again. Pressing that button merely resumes your Calendar Round editing session where you left off. Or you can pick one of six buttons labeled with choices which are guaranteed to result in a valid combination. There are two Haab buttons and four Tzolkin buttons. The two Haab buttons surround the Haab date you specified and are compatible with the Tzolkin date you specified. The four Tzolkin buttons are similar in some way to the Tzolkin you specified, and are compatible with the Haab you specified. (By “similar” is meant: either the day name has changed by the minimum necessary while keeping the day number as you specified; or both the day name and number have changed simultaneously by the minimum amount required for compatibility with the Haab you specified. Note that changing a Tzolkin day number without also changing the day name cannot produce a compatible Tzolkin date.)
3.3 The Month Calendar and Day Selection
3.3.1. The Day Boxes
Most of the main window is taken up by a calendar showing the month selected by the user using the methods described above. For the Mayan calendar, the Haab month is displayed. Each box in the calendar is either blank or has the day of the month in large bold type in the upper right. If a secondary calendar system has been chosen, there are two lines (small type, right-justified in the box) below the day number showing the date in the secondary system. The first of the two small lines shows the day and month (linear calendars) or the Long Count (Mayan). The second shows the year and era( linear) or the Calendar Round date (Mayan).
If the Mayan calendar is the primary system, two or three small lines in the upper left of the box show the Long Count and the Tzolkin date for each day. Whenever the Long Count is shown within a day box, whether the Mayan calendar is the primary or secondary system, any leading zeroes are not displayed (to eliminate clutter from the crowded display). When the Mayan calendar is primary, the 8 Long Count digits are shown separately. The first three (which are unique to InterCal) are shown on the top line in the upper left of each day box. The next five digits appear on the second line. If the Long Count is non-negative and if the first three digits are all zero (which will usually be the case) the top line is not displayed.
If the displayed month contains a holiday which the user has designated for highlighting (see §4.4.2 below) the name of the holiday appears on the next line (left justified). It is possible for holidays to collide (for example, Christmas and Hanukah). In such cases more than one name appears in the box. In case of collision, the highlight colors or patterns appear with the following priority: Christian overrides Jewish which overrides Islamic. This ordering merely reflects the order of checking for holidays in the code. Please do not read any ulterior motives into the ordering—there are none.
If the displayed month includes the selected date (see next subsection) or today’s date, they are also highlighted—always in black and white. The selected date appears in reverse video. Today’s date appears with a light-gray background. On the screen, selection overrides all other highlighting—the selected date always appears in reverse video whether or not it is today’s date or a highlighted holiday. The “today’s date” highlighting overrides holiday highlighting, but not selection. When printing, slightly different rules apply, as explained in detail in §4.1.3 below.
3.3.2. Date Selection
The user may select any displayed date by clicking once in its box. He/she may cause there to be no selected date by clicking on any blank box in the month calendar.
Selecting a date serves two functions. The user may want to mark a date to return to later after exploring other months or years (see §4.4.3). Or you may want to see at a glance that date’s equivalent in all implemented calendars using the date window (see §4.4.1). Causing there to be no selected date serves no apparent function unless the user finds the reverse video box to be aesthetically unappealing, but I had to decide to either ignore clicks in blank boxes or do something. I chose the latter.
Selecting a date by clicking in a box on the month calendar has the side effect of changing displayed date to equal the newly chosen selected date. This was done to simplify the task of switching primary calendars without losing the selected date from the display. If the Mayan calendar is the primary system, you will see the Mayan controls change values. There is another way to select a date which does not require the date to be in the current month calendar display and which has no effect on displayed date. It is described in §4.4.1 below.
